Hop til hovedindhold

D230 Developer Guide

Document status35 - Reviewed

To make it easy to onboard developers and to ensure a uniform way of working, a Developer Guide must tell how it will be possible to contribute to the solution. The guide must answer how a development environment is set up and what technical prerequisites must be met to make it happen. Any requirements for the preparation and storage of code must also be described in the Developer Guide.

Setup a local development environment​

This section describes setting up a running local environment on a developer's machine. Before the developer can follow this guide, they must be added to the "Energy Connect 3 team" in the Azure DevOps project.

  1. Install prerequisites:
  2. Clone our repository using git.
    • If you do this through Rider or VS, they should include/install Git semiautomatically, if it is missing.
  3. Build the solution in the IDE (do not deploy yet). This generates the application's OpenAPI spec.
  4. In an admin Powershell in the root directory:
    1. Set-ExecutionPolicy RemoteSigned - Allows running the scripts in our repository.
    2. $Env:ASPNETCORE_ENVIRONMENT = "Development" - Makes the application see your PC as a Development environment.
    3. .\Infrastructure\Scripts\frontend_api_client_generation\GenerateFrontendModels.ps1
  5. Start Docker Desktop.
  6. Setup docker-compose deployment in the IDE using the "energyConnect" profile, which limits the running services to the essentials.
  7. Run docker-compose from the IDE.
  8. In a Powershell in the root directory:
    • .\Infrastructure\Scripts\migrations\MigrateDatabases.ps1
  9. Open <http://localhost:4200> in a browser to open the application. You will be redirected to the dev login page where you can select your user and roles (see Security during development.

Azure Portal Access​

For access to resources on Azure Portal, the developers need to request the following from IT:

  • A "Proactive Hosting" account.
  • Invitation for the "Proactive Hosting" account to the Directory "ProActive Datahub".
  • Request "Contributer" access to "Energy Connect" subscription from IT.
  • VPN access for the "Proactive Hosting" account to the "hub-dev", "hub-test" and (if needed) "hub-prod" CISCO VPN groups.

The VPN client needed to connect can be found here: vpn.proactive.hosting - log in with the "Proactive Hosting" account, select "hub-test" and you will be presented with a download option. After installing, you can log in with your proactive.hosting credentials.

How to work with the solution​

The following sections describe some of the common patterns that are useful to know during development.

Generating test data​

The database starts out empty by default, but it’s often useful to work with sample data during development. To make that easy, we provide a tool that seeds your local database with some test data.

  1. Ensure that your database is running.
  2. Run the GenerateTestData project.

Checking errors in backend/frontend​

  • Backend build errors - Check your IDE output (Rider / Visual Studio).
  • Frontend build errors - Check the client-dev container logs in Docker Desktop.
  • Backend runtime errors - Check the local log aggregation tool, Seq, at <http://localhost:5341>.
  • Frontend runtime errors - Check the browser DevTools Console and Network tab.

Running backend jobs​

We use Hangfire for scheduled and async background jobs. The Hangfire Dashboard is available on each deployed environment at /hangfire-login (requires the Hangfire Entra role). See Hangfire Job Management for details.

Working with database migrations​

We use Entity Framework Core to generate SQL migrations and keep the database schema in sync with the domain model. Whenever you make a change to the domain model that affects the database schema, you’ll need to create a new migration and apply it to your local database. To assist this we provide some scripts:

  • To create a migration, run .\Infrastructure\Scripts\MakeMigrations.ps1
  • To apply the migrations against the local DB, run .\Infrastructure\Scripts\MigrateDatabases.ps1

Pulling changes and updating the local solution​

The following covers the usual way to pull changes, from the same branch-version that you are already on:

  1. Pull/merge from our repository using Git.
  2. Run docker-compose from the IDE.
  3. Run .\Infrastructure\Scripts\frontend_api_client_generation\GenerateFrontendModels.ps1, if there are changes to the API.
  4. Run .\Infrastructure\Scripts\migrations\MigrateDatabases.ps1, if there are changes to the database.

Resetting the local solution​

The following can be used to reset your local environment. This can be required if you change the branch-version or if your local DB ends in a bad state (bad migration, etc).

  1. Stop all docker containers.
  2. Delete the energy connect containers.
  3. Delete the .\volumes-directory. This is the container volumes, including the local DB data.
  4. Rebuild the solution.
  5. Run .\Infrastructure\Scripts\frontend_api_client_generation\GenerateFrontendModels.ps1
  6. Run docker-compose from the IDE.
  7. Run .\Infrastructure\Scripts\migrations\MigrateDatabases.ps1

Contributing​

See Version Control & Branching Strategy for information about branching.

  1. Pull from the branch you want to change from our repository.
  2. Make your changes and commit them.
  3. Push a new branch dev/[DevOps ID]-[Short meaningful text] or bug/[DevOps ID]-[Short meaningful text] to our repository.
  4. Create a pull request from that branch to the target branch version, e.g. release/3.1. Remember to link the work item you are working on.
  5. When the pull request has been approved by a colleague and completed, it is merged into the target branch.